home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / proto212.zip / EXEMPLE.ZIP / DOCUMENT.EXM next >
Text File  |  1992-01-24  |  4KB  |  89 lines
  1.     Le fichier exemple.zip contient plusieurs fichiers. Nous
  2.     allons présenter les outils de documentation de Solucorp.
  3.     Dans ce document, le mot documentation réfère à quelques formes
  4.     d'information qui aident les programmeurs à comprendre et utiliser
  5.     des librairies logiciels. Nous ne faisons aucunement référence
  6.     à de la documentation pour usager.
  7.  
  8.     Fournir une documentation fiable et à jour n'est pas facile. Une
  9.     méthodologie basée sur un système trop indépendant du
  10.     code source ne fonctionnera pas.
  11.  
  12.     Une documentation fiable (complète et à jour) aide à la réutilisation
  13.     du code. Voici, à notre avis, les éléments essentiels à toute
  14.     réutilisation de code.
  15.  
  16.     A)  Les fonctions doivent être facile à localiser. Les programmeurs
  17.         ont besoin d'indexs, de sommaires, et références. Si une fonction
  18.         ou système existe, mais n'est pas facile à localiser, il
  19.         sera refait (duplicaté).
  20.  
  21.     B)  Une fonction ou groupe de fonctions doit être facile à comprendre.
  22.  
  23.         Chaque fonction d'un système doit être documentée, simplement et
  24.         la documentation doit être très proche du code lui-même.
  25.  
  26.     C)  Le code doit fonctionné correctement !
  27.  
  28.     Le kit de documentation Solucorp part du principe que la documentation
  29.     d'un module doit être dans le code source, immédiatement à coté de
  30.     la déclaration formelle du module (fonction). Si cette documentation
  31.     n'est pas fiable et à jour, aucune ne le sera jamais.
  32.  
  33.     Le format de présentation est simple. La première ligne de
  34.     commentaire avant la déclaration d'une fonction est un description
  35.     brève de la fonction. Tous les commentaires entre cette ligne et
  36.     la déclaration donne une explication plus complète. Cela dit
  37.     ce que la fonction fait et ne fait pas, quand cette fonction
  38.     doit être appelée, ce qui améliorerait cette fonction, les
  39.     valeurs retournées, etc ...
  40.  
  41.     Les fichiers sources (source*.c) fournis présentent un système
  42.     de fonctions avec une documentation très brève. Le fichier makefile
  43.     contient une cible "doc" à la fin, qui montre la série de commande
  44.     utilisée pour mettre à jour le kit de documentation.
  45.  
  46.     A partir des fichiers sources, proto (l'extracteur de prototypes)
  47.     extrait les prototypes et les commentaires entourant les déclaration.
  48.     Le fichier xsys.nap est produit.
  49.  
  50.     Naperm formatte trois fichiers à partir de xsys.nap.
  51.  
  52.     xsys.nas : Toutes les fonctions sont présentées en ordre alphabétique
  53.                accompagnées de la description brève.
  54.     xsys.nai : C'est un index permutté du fichier xsys.nas.
  55.     xsys.nah : C'est un historique de toutes les révisions qui ont été
  56.                faites au projet xsys.
  57.                On peut retrouver quand une fonction a été ajoutée au
  58.                projet. On voie les fonctions qui ont été éliminées.
  59.                Les différentes révisions d'une fonction apparaissent
  60.                aussi.
  61.  
  62.     Si un programmeur a une connaissance minimale du système Xsys,
  63.     ces trois fichiers lui-permettront de localiser rapidement
  64.     les différentes fonctions requises pour son projet.
  65.     Si, par contre, le système est nouveau pour lui, et que Xsys
  66.     possède une centaine de fonctions, un autre document sera requis.
  67.  
  68.     Un document général sur Xsys devra être réalisée. Il présentera
  69.     les fonctions d'une façon organisée. Ce genre de document est
  70.     difficile à produire, impossible à entretenir. Il est généralement
  71.     volumineux. Il est souvent erroné. Pour toutes ces raisons,
  72.     il n'est jamais lu.
  73.  
  74.     Il y a toutefois un moyen de produire un tel document simplement.
  75.     Si la documentation dans les sources est précise, alors un document
  76.     peut être formatté à partir de cela. Le fichier xsys.doc est
  77.     un squelette du manuel de référence du système xsys. Il contient
  78.     un petite introduction, une présentation du système et une
  79.     classification de chacune des fonctions de xsys.
  80.  
  81.     A partir de xsys.doc et xsys.nap, le fichier xsys.ref est produit.
  82.     Ce fichier est le manuel de référence. Il est toujours à date
  83.     (aussi à date que la documentation dans les sources). Nadoc est
  84.     le programme qui produit ce fichier. It mentionne toutes les
  85.     fonctions de xsys qui ne sont pas classifiées dans xsys.doc.
  86.     Il mentionne aussi les fonctions classifiées qui n'existent
  87.     plus dans le système xsys.
  88.  
  89.